Amiga Plus Leser 15/Amiga Plus Leser CD 15.iso/Tools/Development/mmu/MuManual/Autodocs/memory.doc

Text File | 2002-03-12 | 37KB | 1,145 lines

TABLE OF CONTENTS

memory.library/--Background--
memory.library/NewAdrSpaceA
memory.library/DeleteAdrSpace
memory.library/MMUContextOf
memory.library/AdrSpaceOfCtx
memory.library/NewVMPoolA
memory.library/DeleteVMPool
memory.library/LockMemory
memory.library/UnlockMemory
memory.library/HoldMemory
memory.library/UnholdMemory
memory.library/SwapMemoryOut
memory.library/AllocVMemory
memory.library/FreeVMemory
memory.library/PoolVBase
memory.library/PoolVSize
memory.library/EnterAddressSpace
memory.library/LeaveAddressSpace
memory.library/CurrentAddressSpace
memory.library/--Background--            memory.library/--Background--

    PURPOSE
    The memory.library provides functions for memory allocation and
    deallocation that are superior to those of the exec.library.

    The functions of this library provide so called "virtual memory" by using
    the mmu.library, memory that can be swapped to disk transparently to the
    application. Hence, applications will be usually able to allocate more
    memory than physically available.

    Certain access restrictions arise for memory allocated by the memory.library.
    First, you can't access it in Forbid() or Disable() state. Trying to do so
    may certainly cause a fatal "Guru" of the Bus-Error type. The memory.library
    does further not allow you to allocate or release memory while in Forbid()
    or Disable() state, so beware!

    Second, virtual memory cannot be shared amongst different pools. You must
    explicitly attach the tasks that should be able to access memory from a given
    pool. Thus, you can't use this kind of memory for keeping Os structures since
    they may be passed to different tasks for further processing. Use the classic
    AllocMem() for this purpose, it will give you "shared memory" or "shareable
    memory".

    Third, you MAY NOT access virtual memory in a situation where file I/O would
    be impossible. That is, DO NOT access this mem while:
        - disabling the filing system of the swap partition if you're using
          a file based swapping mechanism
        - making the swapping exec device unaccessible
        - taking over the hardware
    The mmu.library will try to detect such situations and will throw a guru
    whenever possible. However, if it is not, these situations will result
    in a dead-lock! Keep care!


    OBJECTS:

    Two new objects are introduced by the memory library: The "AddressSpace"
    and the "VMPool". Both objects have no documented structure and should
    not be touched by your application directly. Similarly to the MMUContext
    of the mmu.library, these two should be understood as "magic cookies"
    that have to be passed into the functions of the memory.library.

    The AddressSpace is an extension of the "MMUContext" of the mmu.library;
    it defines a "meaning" to addresses for all tasks that are part of a
    certain address space. Hence, a "Task" in the exec sense should be
    understood as a "thread" in the sense of Un*x, and an "AddressSpace" as
    the analogue of a "process" as all tasks that are part of an
    "AddressSpace" share common addresses. Tasks must enter and leave
    address spaces explicitly by functions provided by this library.

    Each MMUContext can hold *at most one* AddressSpace, not more. In case
    you want to build a new address space, you are hence strongly encouraged
    to build a private MMUContext of the "shared" type, see the mmu.library
    documentation for details. Do not try to attach an address space to the
    public MMUContext.

    A VMPool can be understood as the analogue of the memory pools of the
    exec.library. Each AddressSpace can hold as many pools as you need,
    each of them with a well-defined set of caching modes and memory
    property flags. You may even define a private swapping mechanism on a
    per-pool basis.

    A VMPool need not to carry memory that is available for allocation
    by means of AllocVMemory() resp. FreeVMemory(). A VMPool can also hold
    the image of a file which is, as a whole, mirrored in memory. The
    file contents can then be altered simply by working on the image in
    memory, without even requiring to hold the file in memory completely.
    Swapping will happen automatically and completely transparent to your
    application. This is similar to the Un*x mmap() feature.


    The restriction that virtual memory cannot be accessed during Forbid()
    or Disable() can be weakened somewhat by the LockMemory/UnlockMemory
    resp. HoldMemory/UnholdMemory functions. Where the first pair
    guarantees that the addressed memory cannot be flushed out and hence
    remains valid within Forbid()/Disable(), the second pair even returns
    a continuous *physical* memory block that can be transfered to and
    from disk using traditional I/O mechanisms. Note that LockMemory()
    does not allow this as a "logical" memory block may be fragmentated
    into several physical memory blocks that do not form a continuous
    memory block by their physical addresses. As both functions require
    the complete memory block to fit into the system main memory, you are
    encouraged to hold locks as short as possible.

    This kind of "virtual memory" is of course some kind of a "poor man's
    solution" for implementing virtual memory. No exec function will be
    patched and old programs will continue to work without any change. The
    library is of course of limited or no use at all for old programs since
    it doesn't redirect standard memory allocation functions to their
    "virtual" counterparts. Thus, this is a very "conservative" approach to
    overcome this limitation of AmigaOs.

    A special "VMM/GigaMem" is planned to be made available that uses the
    functions of this library to provide virtual memory to every task.
    However, since this CAN'T be fully compatible to old programs and may,
    therefore, cause some compatibility problems. It should be up to the
    user if she/he likes to install a patch like this or not, but it should
    NOT the way how virtual memory enters AmigaOs, at least not now.

memory.library/NewAdrSpaceA            memory.library/NewAdrSpaceA

    NAME
    NewAdrSpaceA    -    create a new address space.

    SYNOPSIS
    adr = NewAdrSpaceA( tags );
    d0             a0

    struct AdrSpace *NewAdrSpaceA( struct TagItem * );

    adr = NewAdrSpace( tag, ... );

    struct AdrSpace *NewAdrSpace( Tag tag1, ... );

    FUNCTION
    Builds a new address space of the given properties, to be
    passed in as a tag list. Note that this call *does not* attach
    any task to the address space, neither does it involve the
    creation of any memory pool.

    INPUTS
    tags -    a tag list containing the arguments how the address
    space has to be build.

    RESULTS
    a new address space or NULL on failure. In case this function
    is called from a dos.library "Process", IoErr() will be set to
    a secondary error code on failure. See <memory/memerrors.h>
    for details.

    TAGS
    The following tag items are interpreted:


    MEMTAG_CONTEXT
        The mmu.library MMUContext the address space shall
        become part of. At most one address space per context;
        DO *NOT* attach an address space to the public context
        or to a supervisor context, this won't work.
        Default is the context the MEMTAG_TASK task is part of.

    MEMTAG_TASK
        If MEMTAG_CONTEXT is missing, this tag can be used to
        specify the target context. The MMUContext this task
        is part of will then be used as target for the new
        AddressSpace. Default is the current task.

    MEMTAG_SWAPFAILHOOK
        A pointer to a "struct Hook" that will be called
        whenever swapping memory in or out fails. See the
        "Programmer's manual" for details how you are called.

    MEMTAG_VMSIZE
        Size of virtual memory area to be handled by this
        address space, not including shared system memory.
        Default is as large as the system, the swapping
        device and MEMTAG_VMMAXSIZE (see below) allows.

    MEMTAG_VMMAXSIZE
        Limits the size of the virtual memory region to be
        allocated to the indicated size. The resulting address
        space will hold at most the indicated size, but might
        hold less due to limitations of the swap device.

    MEMTAG_MAXSYSMEM
        Maximal amount of physical system memory this address
        space is allowed to allocate. If a new page must be
        swapped in, the total amount of physical page memory
        held by this address space is compared against this
        threshold. If it is larger, pages are swapped out.
        However, if you hold locks on memory by LockMemory()
        resp. HoldMemory(), the library may ignore this
        threshold temporarely as long as you hold the locks.
        I.e., locking will not fail due to this threshold as
        long as enough system memory is available.
        Default is half the system memory minus a safety
        margin.

    MEMTAG_CACHESIZE
        Defines the size in bytes of an additional write cache
        that is used to minimize the seeking within a swap
        file or swap partition/device. This cache keeps swapped
        out pages and is written out "in one go" as soon as
        necessary. Defaults to sixteen pages, or no write cache
        if MEMTAG_READONLY,TRUE has been found. The memory type
        of the cache is controlled by MEMTAG_BUFMEMTYPE, and
        defaults to MEMF_PUBLIC.

    MEMTAG_WINDOWPTRPTR
        Defines a pointer to a window pointer - note the double
        indirection - where error requesters concerning the
        virtual memory system will appear. If the pointer the
        argument is set to (struct Window *)(~0), no requesters
        will be generated as if the requester got canceled,
        if set to NULL, requesters will appear on the workbench.
        Default is NULL, or a pointer to the pr_WindowPtr
        component of the MEMTAG_TASK, should this tag be present.

    MEMTAG_VMHOOK
        A custom defined swap hook as "struct Hook *" that
        will be called for swapping activities. Either this
        or the next tag must be given to define a swapping
        mechanism.

    MEMTAG_VMSWAPTYPE
        Defines a library pre-defined swap hook as swapping
        mechanism; this is the prefered option. The following
        swap types are available:

        MEMFLAG_SWAPFILE
            Swap to a dos.library file.
            Note that this is slow for the FFS, but is the
            least critical way to provide a swap target.

        MEMFLAG_SWAPPART
            Swap to a dos.library "Device"
            in the sense of a partition on a hard disk. This is
            the best compromise between speed and safety.

        MEMFLAG_DEVICE:
            Swap to an exec.library
            "device" given by a device name and a unit.

    The following are only for MEMFLAG_SWAPFILE:

    MEMTAG_SWAPFILENAME
        A "char *" to the name of the swap file. Must be
        present for file swapping.

    MEMTAG_SWAPFILELOCK
        A lock onto a directory the above file name is
        relative to. Defaults to the current directory of
        the calling process.

    MEMTAG_KEEPFILE
        If set to TRUE, the file is not deleted if the
        AddressSpace is shut down. Defaults to FALSE, i.e.
        the file will be deleted when done.

    MEMTAG_PREDEFINED
        If set to TRUE, the swap file is assumed to be
        existent already and the contents of this file
        is mirrored into the virtual memory. Defaults to
        FALSE. Most useful with MEMTAG_KEEPFILE.

    MEMTAG_READONLY
        Requires MEMTAG_PREDEFINED set to true and
        allows reading from the swap file only to browse
        it in memory. Any changes made to the memory are
        discarded. Should be combined with the MMU
        property MAPP_ROM or MAPP_READONLY for the pools
        of this address space for optimal performance.
        Defaults to FALSE.


    The following are only for MEMFLAG_SWAPPART:

    MEMTAG_SWAPDEVICENODE
        A pointer to a dos.library "struct DeviceNode" that
        defines the swap partition. Either this or the next
        tag must be given to specify a swap partition.

    MEMTAG_SWAPPARTNAME
        The dos.library device name of the swap partition as
        "char *" with or without trailing colon, e.g. "SWAP:"

    The following are only for MEMFLAG_SWAPDEVICE:

    MEMTAG_DEVICENAME
        The name of an exec.library "device" to which memory
        shall be swapped. This must be a "trackdisk"-like
        device that allows random access. This tag must be
        available.

    MEMTAG_DEVICEUNIT
        Unit number of the above device to swap to. Defaults
        to zero.

    MEMTAG_DEVICEFLAGS
        Flags for "OpenDevice()" for this device. Defaults to
        zero.

    MEMTAG_BUFMEMTYPE
        Intermediate buffer memory type for the device in
        case the device is unable to perform I/O on all system
        memory addresses. Default is MEMF_24BITDMA. Note that
        this is a very conservative setting that should work
        with all devices; you might want to specify MEMF_ANY
        here. Note further that the memory.library never
        passes "logical addresses" to the swapping device, but
        always already translated physical addresses.

    MEMTAG_MASK
        Memory mask to check the memory against. If the
        output buffer "and-ed" with the complement of this
        mask is non-zero, the device swap hook will use
        single-block I/O to perform the operation. Note that,
        similar to the above, you *need not* to specify a
        mask to exclude virtual memory. The library will
        always pass physical addresses to the device.
        Default is 0x00fffffc, which is a very conservative
        setting and allows only device access within the
        24 bit address space. A well-written device driver
        will accept 0xffffffff here.

    MEMTAG_MAXTRANSFER
        The size of the largest memory block this device
        will be able to access at a time. Defaults to
        0x001fe000.

    MEMTAG_DEVICESIZE
        Size of the area to be reserved for the swapping
        activities. Limited by 2GB. Note that due to the
        broken design of many devices, i.e. lack of support
        for TD_GETGEOMETRY, this size cannot be obtained
        safely from the device itself.

    MEMTAG_DEVICEORIGIN
        Byte offset from the beginning of the device to the
        first block of the device where swapped data will
        be held. This is a pointer to a "QUAD word", i.e.
        a two-ULONG array containing the high and low
        ulong-word defining the size as 64 bit integer.
        If any part of the swap area exceeds the 64 bit
        limit, the device must be either TD64 or NSD
        compliant with the further restriction that
        NSDPatch must be running to activate NSD activities.

    MEMTAG_SECTORSIZE
        Size of a sector (or "block") of the device in
        bytes. This value is only used for single-block
        transfers and defaults to 512 bytes.

    NOTES
    This call builds a new address space, but does neither create
    any pools nor does it attach the calling task to the address
    space. You need to do this manually, i.e. build a pool by
    NewVMPool() and enter this address space by EnterAddressSpace().

    To mirror the contents of a file into memory (i.e. to emulate
    "mmap") the following tags should be used:


            adr = NewAdrSpace(
                MEMTAG_VMSWAPTYPE,MEMFLAG_SWAPFILE,
                MEMTAG_SWAPFILENAME,"MyMMAPTarget",
                MEMTAG_KEEPFILE,TRUE,
                MEMTAG_PREDEFINED,TRUE,
                TAG_DONE);

    For a classical swap partition, the following combination
    is useful:

            adr = NewAdrSpace(
                MEMTAG_VMSWAPTYPE,MEMFLAG_SWAPPART,
                MEMTAG_SWAPPARTNAME,"SWAP:",
                MEMTAG_VMSIZE,128*1024*1024, /* e.g. 128MB */
                TAG_DONE);

    Note that - similar to all other Os calls - the tags and its
    arguments must be placed in shared system memory.

    BUGS
    The device and partition swap hook expect currently that the block
    size of the responsible exec.device is a multiple of the page size.
    This rules page sizes of 256 bytes out - as they are available on a
    68030 or 68020/68851 combo. Further, this doesn't allow swap devices
    whose block sizes are not a power of two (as for example CDs - but
    who wants to swap to a CDRW anyhow?)

    SEE ALSO
    DeleteAdrSpace(), mmu/CreateMMUContext(), EnterAddressSpace(),
    dos/IoErr(),
    memory/memtags.h, memory/memerrors.h

memory.library/DeleteAdrSpace                    memory.library/DeleteAdrSpace

    NAME
    DeleteAdrSpace    -    delete an address space.

    SYNOPSIS
    DeleteAdrSpace( adr );
             a0

    void DeleteAdrSpace( struct AdrSpace * );

    FUNCTION
    This call deletes the specified address space, unlinks it from its
    MMUContext, disposes all VMPools of this address space and closes
    all swap hooks, possibly deleting all swap files.

    INPUTS
    adr    -    pointer to the address space to dispose.

    RESULTS
    none

    NOTES
    You should unlink your task from the MMUContext as well and dispose
    this context as well; this function will *not* do this for you.
    Note that you should not attach AddressSpace(s) to the public MMU
    context.

    BUGS

    SEE ALSO
    CreateAdrSpaceA(), mmu/DeleteMMUContext()

memory.library/MMUContextOf                memory.library/MMUContextOf

    NAME
    MMUContextOf    -    return the underlying MMUContext of an
                AddressSpace

    SYNOPSIS
    ctx = MMUContextOf( adrspace );
    d0               a0

    struct MMUContext *MMUContextOf( struct AdrSpace *);

    INPUTS
    adrspace - pointer to a struct AdrSpace whose underlying MMUContext
    shall be obtained

    RESULTS
    ctx - the MMUContext handling the MMU setup of the passed in Address
    space.

    NOTES
    This call cannot fail.

    BUGS

    SEE ALSO
    AdrSpaceOfCtx()
memory.library/AdrSpaceOfCtx            memory.library/AdrSpaceOfCtx

    NAME
    AdrSpaceOfCtx    -    return the AdressSpace a MMUContext is
    attached to.

    SYNOPSIS
    adr = AdrSpaceOfCtx( ctx );
    d0              a0

    struct AdrSpace * AdrSpaceOfCtx( struct MMUContext * );

    INPUTS
    ctx - a pointer to a struct MMUContext whose AddressSpace shall be
    obtained.

    RESULTS
    the AddressSpace the passed in MMUContext is attached to or NULL
    in case it is not attached to any AddressSpace.

    BUGS

    SEE ALSO
    MMUContextOf()
memory.library/NewVMPoolA                memory.library/NewVMPoolA

    NAME
    NewVMPool    -    create a new virtual memory pool

    SYNOPSIS
    pool = NewVMPoolA( tags );
    d0            a0

    struct VMPool * NewVMPoolA( struct TagItem *tags);


    pool = NewVMPool( tag, ... );

    struct VMPool * NewVMPool( Tag tag1, ... );

    FUNCTION
    Creates a new pool providing virtual memory within an AddressSpace.

    INPUTS
    tags - a list of TagItems describing the properties of the VMPool
    to be created, see below.

    RESULTS
    a pointer to a new memory pool structure or NULL on failure. If
    the calling task is a dos.library "process", then IoErr() will be
    set to an error code defined in dos/dos.h or memory/memerrors.h
    on failure.

    TAGS
    The following tags are available for building new VMPools:

        The next three are used to specify the AddressSpace for
        the new pool:

        MEMTAG_ADRSPACE
            A pointer to the AddressSpace within which this
            pool shall be created.

        MEMTAG_CONTEXT
            A pointer to a MMUContext that is attached to
            an AddressSpace; the pool will then be build within
            the AddressSpace that is attached to the specified
            MMUContext.

        MEMTAG_TASK
            A pointer to a struct Task that is attached to
            an AddressSpace; the pool will be build within this
            AddressSpace. Defaults to the current task.

        If either this or the next tag is present, the pool will
        get its own swapping mechanism; otherwise, the same swap
        hook than the parent AddressSpace will be used:

        MEMTAG_VMHOOK
            A custom defined swap hook as "struct Hook *" that
            will be called for swapping activities.

        MEMTAG_VMSWAPTYPE
            Defines a library pre-defined swap hook as swapping
            mechanism.

        See NewAdrSpaceA() for further tags related to the swap
        hook specification; all of them are valid here as well.
        Using a private swap hook requires MEMTAG_FIXEDSIZE set
        to TRUE, and therefore MEMTAG_PREDEFINED set to TRUE as
        well.


        Further extended tags:

        MEMTAG_PREALLOC
            If set to TRUE, the pool memory will be allocated
            already at full size from the available virtual
            memory space of the AddressSpace on setup. Otherwise,
            memory puddles are build as soon as required.
            MEMTAG_PREALLOC, TRUE must be specified if you want
            to map a file into memory.
            Defaults to FALSE.

        MEMTAG_MEMFLAGS
            exec/memory.h type memory properties describing
            the physical memory to be allocated for this pool.
            Defaults to MEMF_ANY.

        MEMTAG_CACHEFLAGS
            mmu/context.h type "MMU properties" of the memory
            to be addressed by the context. This defaults
            to the optimal caching mode of the memory the
            library allocated for its pages. Useful    flags are:

            MAPP_COPYBACK:    Make the memory copyback-cacheable.
                    If cleared explicitly, the caching
                    mode is writethrough.
            MAPP_CACHEINHIBIT: Forbid caching in the allocated
                    pages.
            MAPP_NONSERIALIZED: Allow access reordering for the
                    68040 if cache inhibited; ignored
                    otherwise.
            MAPP_IMPRECISE:    Allow imprecise exception model for
                    the 68060 if caching is inhibited;
                    ignored otherwise.
            MAPP_ROM:    Defensive write protection. Useful
                    for "read only" images of files.
            MAPP_WRITEPROTECTED: Aggressive write protection,
                    write access causes an access error
                    and therefore either a Guru or a
                    MuForce hit.

        MEMTAG_CACHEMASK
            mmu/context.h mask describing which caching flags
            shall be altered. Note that the memory.library may
            ignore some of your choices because it requires some
            flags for its own purposes.

        MEMTAG_PUDDLESIZE
            Size of a memory puddle in bytes that will be
            created if a memory block runs out of data. Puddles
            are enforced to be at least one MMU page large.
            Defaults to eight pages.

        MEMTAG_PUDDLETHRES
            Threshold defining which allocations go into separate
            puddles and which allocations are taken from the
            common puddles. Default is half the puddle size.

            NOTE: The puddling mechanism of the memory.library
            works *not* like that of exec.library. Do not
            expect any exec.library compatible memory pools.

        MEMTAG_POOLPRI
            Priority of this pool. Higher priority pools will
            be swapped out later. Defaults to zero.

        MEMTAG_FIXEDSIZE
            Do not allow the creation of new puddles. Only use-
            ful if MEMTAG_PREALLOC is set to TRUE as well or
            you won't be able to allocate any memory. Defaults
            to FALSE.

        MEMTAG_PROVIDESMEM
            Set to TRUE in case this pool can be used to allocate
            virtual memory; if FALSE, this pool is rather used
            as a mirror of the swap space, or available for your
            own memory allocation routines. Defaults to TRUE,
            should be set to FALSE for an "mmap" emulation.

        MEMTAG_PREDEFINED
            The pool contents is pre-defined by the contents of
            the swap space. Only useful if you want to mirror the
            swap space into memory for "mmap" emulation.
            Defaults to FALSE.

        MEMTAG_READONLY
            Changes made to the pool are not written back to
            swap space. Requires MEMTAG_PROVIDESMEM set to FALSE
            or the pool will become corrupt as soon as it must
            be swapped. Defaults to FALSE.

    NOTES
    Useful pool options for "mmap" are as follows:


        vmpool = NewVMPool(    MEMTAG_ADRSPACE,adr,
                    MEMTAG_PREDEFINED,TRUE,
                    /* MEMTAG_READONLY,TRUE, for read-only files */
                    MEMTAG_PREALLOC,TRUE,
                    MEMTAG_PROVIDESMEM,FALSE,
                    MEMTAG_FIXEDSIZE,TRUE,
                    TAG_DONE);

    Then use PoolVBase() to obtain the virtual base address of the swap
    file in memory.

    Useful options for virtual memory operations are:


        vmpool = NewVMPool(    MEMTAG_ADRSPACE,adr,
                    MEMTAG_PROVIDESMEM,TRUE,
                    /* MEMTAG_MEMFLAGS,MEMF_CLEAR, */
                    TAG_DONE);

    Then use AllocVMemory() and FreeVMemory() to allocate and release
    virtual memory. Note that MEMF_CLEAR might be very expensive since
    clearing the memory might cause the library swap in/out the blanked
    memory.

   SEE ALSO
    NewAdrSpaceA(), PoolVBase(), AllocVMemory(), FreeVMemory(),
    dos/IoErr(),
    memory/memerrors.h, memory/memtags.h
memory.library/DeleteVMPool                memory.library/DeleteVMPool

    NAME
    DeleteVMPool - Delete a virtual memory pool

    SYNOPSIS
    DeleteVMPool( pool );
               a0

    void DeleteVMPool( struct VMPool *);

    FUNCTION
    Deletes the given virtual memory pool, releases the memory occupied
    by the pool.

    INPUTS
    pool a handle to a VMPool as created by NewVMPoolA().

    RESULTS
    nothing

    NOTES
    In case the pool was created with MEMTAG_PREDEFINED,TRUE, this
    call also ensures that all changes to the memory are again swapped
    out before the swap hook is closed again.

    SEE ALSO
    NewVMPoolA()
memory.library/LockMemory               memory.library/LockMemory

    NAME
    LockMemory - lock virtual memory in physical space

    SYNOPSIS
    ok = LockMemory( adr, mem, size );
    d0         a0   a1   d0

    BOOL LockMemory( struct AdrSpace *,APTR,size);

    FUNCTION
    The specified memory region in the selected address space is swapped
    in and locked in physical memory. It will not be swapped out until
    you unlock it again. This call nests.

    INPUTS
    adr - the address space the memory is part of. Need not to be the
    address space of the calling task.
    mem - (virtual) start address of the memory to lock.
    size - size of the virtual memory to lock.

    mem and size will be rounded down resp. up to multiples of the
    page size.

    RESULTS
    a boolean success/failure indicator. This call may fail if not
    enough physical memory is available to hold the entire range.

    NOTES
    Even though the memory region will be represented in physical
    space after you locked it, it need not to be represented as a
    single continuous block. It is likely that it is fragmented
    into several discontinuous blocks. Therefore, this routine does
    not return any physical address. Use HoldMemory() for that.

    Note that this call nests.

    BUGS

    SEE ALSO
    UnlockMemory(), HoldMemory()
memory.library/UnlockMemory               memory.library/UnlockMemory

    NAME
    UnlockMemory - unlock virtual memory and re-allow swapping

    SYNOPSIS
    UnlockMemory( adr, mem, size, force);
              a0   a1    d0    d1

    void UnlockMemory(struct AdrSpace *,APTR,ULONG size,BOOL force);

    FUNCTION
    The specified memory region of the address space is unlocked again.
    If the last lock is unlocked again, swapping the memory region
    is re-allowed. The memory region passed in here should match one
    of the regions previously locked with LockMemory().

    INPUTS
    adr - Address space whose memory shall be unlocked.
    mem - (virtual) start address of the memory to be unlocked.
    size - size of the memory region to unlock
    force - if FALSE, this call nests with a previous LockMemory().
        if TRUE, this call resets all lock counts immediately.

    mem and size will be rounded down resp. up to multiples of the
    page size.

    RESULTS
    nothing

    NOTES
    Uses "force = TRUE" with care. It ignores the nesting and
    hence the design of LockMemory().

    BUGS

    SEE ALSO
    LockMemory(), UnholdMemory()
memory.library/HoldMemory            memory.library/HoldMemory

    NAME
    HoldMemory - hold and lock memory in a continuous physical block

    SYNOPSIS
    physical = HoldMemory( adr, mem, size );
    d0            a0   a1   d0

    APTR HoldMemory( struct AdrSpace *,APTR,size);

    FUNCTION
    The specified memory region in the selected address space is swapped
    in and locked in a continuous block of physical memory. It will not be
    swapped out until you unhold it again. This call nests.

    INPUTS
    adr - the address space the memory is part of. Need not to be the
    address space of the calling task.
    mem - (virtual) start address of the memory to lock.
    size - size of the virtual memory to lock.

    mem and size will be rounded down resp. up to multiples of the
    page size.

    RESULTS
    the physical address of the memory block containing the memory region
    or NULL in case the physical memory is not available.

    NOTES
    This call guarantees that the specified memory region is held
    entirely and continuously in physical memory. Note that this is
    a relatively "costy" operation and might require moving major
    parts of data around. Hence, try to avoid this call and use
    LockMemory() whenever applicable.

    Note that this call nests.

    BUGS

    SEE ALSO
    UnholdMemory(), LockMemory()
memory.library/UnholdMemory               memory.library/UnholdMemory

    NAME
    UnholdMemory - unlock virtual memory and re-allow swapping

    SYNOPSIS
    UnholdMemory( adr, mem, size, force);
              a0   a1    d0    d1

    void UnholdMemory(struct AdrSpace *,APTR,ULONG size,BOOL force);

    FUNCTION
    The specified memory region of the address space is unlocked again.
    If the last lock is unlocked again, swapping the memory region
    is re-allowed. The memory region passed in here should match one
    of the regions previously locked with HoldMemory().

    INPUTS
    adr - Address space whose memory shall be unlocked.
    mem - (virtual) start address of the memory to be unlocked.
    size - size of the memory region to unlock
    force - if FALSE, this call nests with a previous HoldMemory().
        if TRUE, this call resets all lock counts immediately.

    mem and size will be rounded down resp. up to multiples of the
    page size.

    RESULTS
    nothing

    NOTES
    Uses "force = TRUE" with care. It ignores the nesting and
    hence the design of HoldMemory().

    BUGS

    SEE ALSO
    HoldMemory(), UnlockMemory()
memory.library/SwapMemoryOut            memory.library/SwapMemoryOut

    NAME

    SwapMemoryOut    -    swap a virtual memory block out.

    SYNOPSIS

    ok = SwapMemoryOut( adr, mem, size );
    d0            a0   a1   d0

    BOOL SwapMemoryOut( struct AdrSpace, APTR mem, ULONG size);

    FUNCTION
    swaps the selected memory region of the specified address space
    out to the swap device. The locked or held parts of the selected
    memory blocks remain in memory, though.

    INPUTS
    adr - address space whose memory shall be swapped out
    mem - (logical) base address of the memory area to swap out
    size - size in bytes of the memory region to swap out

    mem and size will be rounded down resp. up to multiples of the
    page size.

    RESULTS
    a boolean success/failure indicator. On FALSE, your SwapFault
    hook will have been called already.

    NOTES
    This call swaps memory out on demand. This might be a good thing
    to do for telling the library that certain memory regions are
    currently not required. This call does *not* override any locks
    or helds of the regions involved; if parts of the selected
    memory block is locked or held, these parts, and only these
    parts, remain untouched.

    BUGS

    SEE ALSO
    LockMemory(), HoldMemory()
memory.library/AllocVMemory            memory.library/AllocVMemory

    NAME

    AllocVMemory    -    allocate virtual memory from a pool


    SYNOPSIS
    mem = AllocVMemory( pool, bytesize);
    d0             a0         d0

    APTR AllocVMemory( struct VMPool *, ULONG);

    FUNCTION
    This function allocates memory from a given virtual pool.

    INPUTS
    pool - The pool to allocate the memory from.

    bytesize - The size of the memory required. This might be larger
    than the amount of physical memory available.

    RESULTS
    the memory block allocated or NULL for failure. If the calling
    task is a process, the reason for failure will be returned by
    IoErr().

    NOTES
    This call may cause task reschelduringe. It may swap out pages of
    virtual memory if necessary. This call will fail(!) if you call
    it within a Forbid() or Disable() state.

    The returned memory will be aligned to at least a longword bondary,
    the size might be rounded somewhat, but will at least contain the
    number of bytes specified by the argument.

    To be able to allocate memory from the pool, the calling task
    must have been entered the AddressSpace of the selected pool. See
    EnterAddressSpace().

    BUGS

    SEE ALSO
    FreeVMemory(), EnterAddressSpace(), dos/IoErr(),
    exec/memory.h, memory/memerrors.h
memory.library/FreeVMemory            memory.library/FreeVMemory

    NAME
    FreeVMemory - release virtual memory

    SYNOPSIS
    FreeVMemory( pool , mem , bytesize);
              a0     a1         d0

    void FreeVMemory( struct VMPool *, APTR mem, ULONG size);

    FUNCTION
    This function releases virtual memory back into the pool.

    INPUTS
    pool -    the pool the memory was taken from. Must match the pool of
        AllocVMemory()

    mem  -    the memory pointer to be released. It is safe to pass NULL
        here. No action is performed then.

    bytesize - size of the memory block to release. *MUST* match the
           size parameter of AllocVMemory.

    RESULTS
    none

    NOTES
    The caller *MUST NOT* be in Forbid() or Disable() state. If this
    rule is not followed, a bus error "Guru 80000002" or a MuForce
    hit might be the result. This call might swap virtual memory pages
    in or out.

    To be able to call this function, the calling task must have entered
    the AddressSpace the pool is part of. See EnterAddressSpace() for
    details.

    SEE ALSO
    AllocVMemory(), EnterMMUContext()
memory.library/PoolVBase            memory.library/PoolVBase

    NAME
    PoolVBase - return the logical base address of a memory pool

    SYNOPSIS
    mem = PoolVBase( pool );
    d0          a0

    APTR PoolVBase ( struct VMPool *);

    FUNCTION
    This function returns the base address of the virtual memory block
    the memory pool consists of. However, this call is guaranteed to
    work *ONLY* if the pool has been setup with the tags

    MEMTAG_PROVIDESMEM,FALSE,
    MEMTAG_PREDEFINED,TRUE,

    to declare a non-administrated pool.

    INPUTS
    pool - pointer to a VMPool structure as obtained from NewVMPoolA().

    RESULTS
    a pointer to the first logical address managed by the pool or NULL
    in case of failure.

    NOTES
    This call will fail if the pool has been setup for usage of the
    virtual memory allocation pair AllocVMemory() resp. FreeVMemory().
    Use this pair of functions to obtain logical addresses then.

    The purpose of this call is either to implement a private memory
    management within the pool memory, or to get the base address of a
    mirror image of a file if you use this pool as "mmap" emulation.

    BUGS

    SEE ALSO
    PoolVSize(), NewVMPoolA(), AllocVMemory(), FreeVMemory()
memory.library/PoolVSize            memory.library/PoolVSize

    NAME
    PoolVSize - get the size of a virtual memory pool

    SYNOPSIS
    size = PoolVSize( pool );
    d0           a0

    ULONG PoolVSize( struct VMPool * );

    FUNCTION
    Returns the size in bytes of the passed in memory pool. Hence, the
    pool covers the virtual addresses from PoolVBase(..) up to
    PoolVBase(..) + PoolVSize(..), exclusive. However, this call is
    guaranteed to work *ONLY* if the pool has been setup with the tags

    MEMTAG_PROVIDESMEM,FALSE,
    MEMTAG_PREDEFINED,TRUE

    to declare a non-administrated pool.

    INPUTS
    pool -    a handle to the virtual memory pool whose size shall be
        obtained.

    RESULTS
    the pool size in bytes, or 0 in case of failure.

    NOTES
    This call will fail if the pool has been setup for usage of the
    virtual memory allocation pair AllocVMemory() resp. FreeVMemory().

    The purpose of this call is either to implement a private memory
    management within the pool memory, or to get the size of a mirror
    image of a file if you use this pool as "mmap" emulation.

    Note that in the latter case, the size of the pool might be larger
    than the file size due to the MMU page granularity. In fact, pool
    sizes will always be multiples of the MMU page size, whatever it
    might be.

    BUGS

    SEE ALSO
    PoolVBase(), NewVMPoolA(), AllocVMemory(), FreeVMemory()
memory.library/EnterAddressSpace         memory.library/EnterAddressSpace

    NAME
    EnterAddressSpace - attach a task to an address space


    SYNOPSIS
    ok = EnterAddressSpace( adr , task );
    d0            a0    a1

    BOOL EnterAddressSpace(struct AdrSpace *adr,struct Task *task);

    FUNCTION
    This call makes the specified task enter the address space; If this
    call succeeds, the task may use all the VMPools of the address-
    space.

    INPUTS
    adr -     address space to enter
    task -    task that is supposed to enter an address space

    RESULTS
    a boolean success/failure indicator. Will be TRUE on success,
    FALSE otherwise.

    NOTES
    Note that you *must* enter address spaces explicitly to use their
    VMPools. NewAdrSpaceA() won't do this for you.

    This call also (implicitly) enters the MMUContext of the AddressSpace
    and hence overloads the tc_Switch and tc_Launch vectors of the
    specified task.

    BUGS

    SEE ALSO
    LeaveAddressSpace()
memory.library/LeaveAddressSpace        memory.library/LeaveAddressSpace

    NAME
    LeaveAddressSpace - remove the calling task from an address space.

    SYNOPSIS

    ok = LeaveAddressSpace( task );
    d0             a1

    BOOL LeaveAddressSpace( struct Task *);

    FUNCTION
    Remove the calling task from its address space and let it enter    the
    public MMUContext again. The address space itself will continue    to
    exist.

    INPUTS
    task - pointer to the task that shall leave its address space

    RESULTS
    a boolean success/failure indicator. Will return FALSE for
    incorrect parameters, but is otherwise not fail-able.

    NOTES
    The current task is, after calling this function, no longer allowed
    to use any virtual memory allocated by the memory.library.

    It is safe to call this function if the current task isn't attached
    to any address space. Nothing will happen in this case except a
    FALSE result code.

    SEE ALSO
    EnterAddressSpace()